---
title: 'Sample app'
sidebarTitle: 'Sample app'
description: 'A practical demonstration of integrating Nango in your codebase.'
---

The sample app contains:
- **A frontend**: lets users connect an integration using the Nango frontend SDK.
- **A backend**: listens to Nango webhooks and consumes the Nango API to read & write data.

<Frame>
  <img src="/images/screenshots/sample-app.png" />
</Frame>

The sample app uses Slack, Google Drive, OneDrive for Business, and OneDrive Personal as example integrations and is showcased in this [demo video](https://youtu.be/oTpWlmnv7dM).

### Access the repository

<a href="https://github.com/NangoHQ/sample-app" target="_blank" className="inline-flex items-center gap-3 border border-gray-400 h-7 px-5 py-5 rounded-xl hover:bg-gray-100 hover:dark:bg-gray-800">
  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 1024 1024" fill="currentColor" class="h-5 w-5">
    <path fill-rule="evenodd" clip-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8C0 11.54 2.29 14.53 5.47 15.59C5.87 15.66 6.02 15.42 6.02 15.21C6.02 15.02 6.01 14.39 6.01 13.72C4 14.09 3.48 13.23 3.32 12.78C3.23 12.55 2.84 11.84 2.5 11.65C2.22 11.5 1.82 11.13 2.49 11.12C3.12 11.11 3.57 11.7 3.72 11.94C4.44 13.15 5.59 12.81 6.05 12.6C6.12 12.08 6.33 11.73 6.56 11.53C4.78 11.33 2.92 10.64 2.92 7.58C2.92 6.71 3.23 5.99 3.74 5.43C3.66 5.23 3.38 4.41 3.82 3.31C3.82 3.31 4.49 3.1 6.02 4.13C6.66 3.95 7.34 3.86 8.02 3.86C8.7 3.86 9.38 3.95 10.02 4.13C11.55 3.09 12.22 3.31 12.22 3.31C12.66 4.41 12.38 5.23 12.3 5.43C12.81 5.99 13.12 6.7 13.12 7.58C13.12 10.65 11.25 11.33 9.47 11.53C9.76 11.78 10.01 12.26 10.01 13.01C10.01 14.08 10 14.94 10 15.21C10 15.42 10.15 15.67 10.55 15.59C13.71 14.53 16 11.53 16 8C16 3.58 12.42 0 8 0Z" transform="scale(64)"></path>
  </svg>
  <div>NangoHQ/sample-app</div>
</a>


### Run the sample app

<Steps>
  <Step title="Create an account">
    - Go to [nango.dev](https://app.nango.dev?source=sample-app) and create an account (free).
  </Step>
  <Step title="Create a Slack integration">
    - Go to [Integrations](https://app.nango.dev/dev/integrations?source=sample-app) and create a Slack integration.
    - Set up a Slack app:
      1. Go to [Slack Dev Center](https://api.slack.com/apps) and click **Create New App**.
      2. Select **From scratch** for a simpler flow.
      3. Enter your **App Name** and select a workspace to develop your app in, then click **Create App**.
      4. In the **Basic Information** tab, copy your **Client ID** and **Client Secret**.
      5. Go to **OAuth & Permissions** in the left sidebar.
      6. Under **Redirect URLs**, add `https://api.nango.dev/oauth/callback` and click **Save URLs**.
      7. Under **Scopes** > **Bot Token Scopes**, add:
         - `users:read`
         - `chat:write`
    - Go back to Nango. In the _Authorization_ tab, add:
      - `client_id`: from step 4
      - `client_secret`: from step 4
    - In the _Endpoints_ tab, activate `GET /users` and `POST /send-message`.
  </Step>
  <Step title="Create a Google Drive integration">
    - Go to [Integrations](https://app.nango.dev/dev/integrations?source=sample-app) and create a Google Drive integration.
    - Set up a Google Cloud project:
      1. Go to the [Google Cloud Console](https://console.cloud.google.com/) and create a new project (or select an existing one).
      2. Go to the [API Library](https://console.cloud.google.com/apis/library), search for **Google Drive API**, and click **Enable**.
      3. Go to **APIs & Services** > **OAuth consent screen** and configure it:
         - Select **External** user type (or **Internal** for users within your Google Workspace organization).
         - Fill in the required app information and contact information.
         - Add the scope: `https://www.googleapis.com/auth/drive.readonly`.
         - Add test users if using External user type.
      4. Go to **APIs & Services** > **Credentials** > **Create Credentials** > **OAuth client ID**.
      5. Select **Web application**, enter a name, and add `https://api.nango.dev/oauth/callback` under **Authorized redirect URIs**.
      6. Click **Create** and copy the **Client ID** and **Client Secret**.
      7. Copy the **Project Number** from the Google Cloud console under **IAM & Admin** > **Settings** > **Project Number**.
    - Go back to the Google Drive integration in Nango. In the _Authorization_ tab, add:
      - `client_id`: from step 6
      - `client_secret`: from step 6
      - `scopes`: `https://www.googleapis.com/auth/drive.readonly`
    - In the _Endpoints_ tab, activate `GET /documents` endpoint.
  </Step>
  <Step title="Create a OneDrive for Business integration">
    - Go to [Integrations](https://app.nango.dev/dev/integrations?source=sample-app) and create a OneDrive for Business integration.
    - Register an application in [Microsoft Entra admin center](https://entra.microsoft.com):
      1. Sign in to the Microsoft Entra admin center and search for **App registrations** > **New registration**.
      2. Enter a name (e.g., "Nango OneDrive Integration").
      3. Under **Supported account types**, select **Accounts in any organizational directory** for multitenant apps.
      4. Click **Register** and note the **Application (client) ID** from the Overview page.
      5. Go to **Authentication** > **Add a platform** > **Web** and add `https://api.nango.dev/oauth/callback` as the Redirect URI.
      6. Go to **API permissions** > **Add a permission** > **Microsoft Graph** > **Delegated permissions** and add `Files.Read.All`.
      7. Go to **Certificates & secrets** > **New client secret**, create a secret, and copy the value immediately (you won't see it again).
    - Go back to the OneDrive for Business integration in Nango. In the _Authorization_ tab, add:
      - `client_id`: Application (client) ID from step 4
      - `client_secret`: Client secret value from step 7
      - `scopes`: Add `offline_access` and `.default`
    - In the _Endpoints_ tab, activate `GET /user-files/selected` endpoint.
  </Step>
  <Step title="Create a OneDrive Personal integration">
    - Go to [Integrations](https://app.nango.dev/dev/integrations?source=sample-app) and create a OneDrive Personal integration.
    - Register an application in [Microsoft Entra admin center](https://entra.microsoft.com):
      1. Sign in to the Microsoft Entra admin center and search for **App registrations** > **New registration**.
      2. Enter a name (e.g., "Nango OneDrive Personal Integration").
      3. Under **Supported account types**, select **Accounts in any organizational directory and personal Microsoft accounts**.
      4. Click **Register** and note the **Application (client) ID** from the Overview page.
      5. Go to **Authentication** > **Add a platform** > **Web** and add `https://api.nango.dev/oauth/callback` as the Redirect URI.
      6. Go to **Certificates & secrets** > **New client secret**, create a secret, and copy the value immediately (you won't see it again).
    - Go back to the OneDrive Personal integration in Nango. In the _Authorization_ tab, add:
      - `client_id`: Application (client) ID from step 4
      - `client_secret`: Client secret value from step 6
      - `scopes`: Add `offline_access` and `onedrive.readonly`
    - In the _Endpoints_ tab, activate `GET /user-files/selected` endpoint.
  </Step>
  <Step title="Prepare your env">
    - Install: `NodeJS`, `Docker`. Then run:

    ```sh
    git clone https://github.com/NangoHQ/sample-app.git

    cd sample-app

    nvm use
    npm i
    ```
    - Copy your Nango Secret Key, found in [Environment Settings](https://app.nango.dev/dev/environment-settings?source=sample-app).
    - Create a file to store environment variables and fill in the Nango Secret Key:
    ```sh
    cp .env.example .env
    ```
    - Paste the **Project Number** you copied in step 7 of the Google Drive integration setup into the .env file as `GOOGLE_PROJECT_NUMBER=your_project_number_here`:
    ```
    cd front-end
    cp .env.example .env
    ```
  </Step>
  <Step title="Transfer Nango webhooks locally">
    - This command should be running at all time:

    ```sh
    npm run webhooks-proxy
    ```

    - Copy the URL the command gave you and go to [Environment Settings](https://app.nango.dev/dev/environment-settings?source=sample-app). Set Webhook URL to `${URL}/webhooks-from-nango`, e.g: `https://tame-socks-warn.loca.lt/webhooks-from-nango`.
  </Step>
  <Step title="Launch">
    - Run:
    ```sh
    npm run start
    ```
    - Go to: [http://localhost:3011](http://localhost:3011)
  </Step>
  <Step title="Bonus: Deploy custom functions">
    The above sample app uses pre-built functions, but you can also use custom ones.

    - Set up the Nango CLI:
    ```sh
    npm install -g nango
    cd nango-integrations/
    nango init
    ```
    - Add your Nango Secret Key in NANGO_SECRET_KEY_PROD in `./nango-integrations/.env`.
    - Optionally customize the functions using [this guide](/guides/platform/functions).
    - Deploy the custom functions:
    ```sh
    nango deploy prod
    ```
  </Step>
</Steps>

## File Integration Guide

The sample app includes a complete implementation for integrating file storage providers (Google Drive, OneDrive) with your application. This guide walks you through using and understanding the file integration features.

### Overview

Nango's pre-built file integration allows you to:

1. **OAuth Flow**: Handle authentication using Nango's SDK
2. **File Picker**: Let users select specific files and folders to sync
3. **Document Sync**: Sync metadata for selected files and folders
4. **Document Fetching**: Download individual file contents as needed

### Requirements

- Docker (desktop) installed & running
- NodeJS & NPM installed
- A Nango account (sign up at [nango.dev](https://nango.dev))
- Integration setup completed (see steps above)

### Using the File Integration

After setting up and running the sample app (see steps above), follow these instructions to test the file integration:

1. **Access the sample app**:
   - Open [http://localhost:3011](http://localhost:3011/)
   - Click _Files_ to start the file integration

   <img src="/images/file-storage-integrations/sample-app-home.png" alt="Sample app home page with Files section highlighted" />

2. **Connect your account** (Google Drive, OneDrive, etc.):
   - Click the _Connect_ button on the provider's card
   - In the connection popup, click the _Connect_ button
   - Select your account and authorize the app
   - Click the _Finish_ button to close the modal

   <img src="/images/file-storage-integrations/connect-popup.png" alt="Connect popup with file provider account options" />

   <img src="/images/file-storage-integrations/success-popup.png" alt="Successfully connected to file provider" />

3. **Select files and folders to sync**:
   - Click the _Select Files from [Provider]_ button
   - A file picker modal will appear - **note that each provider has its own native file picker**:
     - **Google Drive**: Uses Google's Drive Picker UI
     - **OneDrive for Business**: Uses Microsoft's file picker for organizational accounts
     - **OneDrive Personal**: Uses Microsoft's file picker for personal accounts
   - Select the files and folders you want to sync using the provider's file picker
   - Click the _Select_ button to confirm your selection

   <img src="/images/file-storage-integrations/select-files.png" alt="Select files and folders from provider" />
   <img src="/images/file-storage-integrations/one_drive_picker.png" alt="Select files and folders from provider" />

4. **View synced files**:
   - The files and folders will be synced to your Nango account and displayed in the UI

   <img src="/images/file-storage-integrations/synced-files.png" alt="Synced files and folders in the UI" />

5. **Download a file**:
   - Click the _Download_ button to download the file to your computer

6. **Disconnect your account**:
   - Click the _Disconnect_ button to disconnect your account and delete your connection from your Nango account

   <img src="/images/file-storage-integrations/disconnect-button.png" alt="Disconnect button" />

### What Happens Under the Hood

The sample app uses Nango to:

1. **Authentication**
   - Authenticate users with file storage providers
   - Show the file picker
   - Handle OAuth flow automatically

2. **File Syncing**
   - Sync selected files & folders
   - Initial sync on selection
   - Periodic updates

   <img src="/images/file-storage-integrations/sync-status.png" alt="Nango dashboard showing sync status and file list" />

3. **File Download**
   - Download raw file content
   - Handle different file types
   - Use Nango's proxy for reliable downloads

### Key Components

#### Frontend Implementation

1. **Authorization Flow**
   The authorization process is implemented in [`front-end/src/api.ts`](https://github.com/NangoHQ/sample-app/blob/main/front-end/src/api.ts):
   - `postConnectSession`: Initiates the OAuth connection
   - `getNangoCredentials`: Retrieves credentials after successful authorization

   The flow works as follows:
   1. Frontend initiates connection via `postConnectSession`
   2. Backend creates a Nango connection session
   3. User is redirected to provider OAuth consent screen
   4. After authorization, user is redirected back to the app
   5. User is shown the provider-specific file picker (Google Drive Picker, OneDrive for Business picker, or OneDrive Personal picker)
   6. Frontend can fetch credentials using `getNangoCredentials`

#### Backend Implementation

1. **Webhook Handler & Data Sync**
   The webhook handling and data sync logic is implemented in [`back-end/src/routes/postWebhooks.ts`](https://github.com/NangoHQ/sample-app/blob/main/back-end/src/routes/postWebhooks.ts):

   Key components:
   - Main webhook handler that verifies signatures and routes requests
   - `handleNewConnectionWebhook`: Processes new file provider connections
   - `handleSyncWebhook`: Handles sync completion and data processing

   The sync process:
   1. Nango syncs files from the provider
   2. Webhook notifies backend of sync completion
   3. Backend fetches records using `nango.listRecords`
   4. File metadata is stored in the database
   5. Deletions are tracked and handled appropriately

2. **File Download with Proxy**
   File download functionality is implemented in [`back-end/src/routes/downloadFile.ts`](https://github.com/NangoHQ/sample-app/blob/main/back-end/src/routes/downloadFile.ts):

   The download process:
   1. Frontend requests file download with file ID and connection ID
   2. Backend uses Nango proxy to fetch file from provider
   3. File is streamed to client with proper headers
   4. Error handling ensures graceful failure

   Key features:
   - Uses Nango proxy for secure file access
   - Proper content type and disposition headers
   - Streaming response for efficient file transfer
   - Comprehensive error handling

### Nango Dashboard

Explore these sections in your Nango account:

1. **Integration Settings**
   - [View Integrations](https://app.nango.dev/dev/integrations)
   - Configure sync settings
   - View integration status

2. **Connections**
   - [View Connections](https://app.nango.dev/dev/connections)
   - Monitor sync status
   - Check connection health

3. **Logs**
   - [View Logs](https://app.nango.dev/dev/logs)
   - Track sync operations
   - Debug issues

### Common Issues and Solutions

1. **Connection Issues**
   - Check Docker is running
   - Verify webhook URL is correct
   - Ensure provider credentials are valid

2. **Sync Problems**
   - Check Nango logs
   - Verify file permissions
   - Monitor sync status

### File Type Support

The sample app supports all file types through Nango's proxy:

- **Regular files** (PDFs, images, documents, etc.)
- **Google Workspace files** (Docs, Sheets, Slides)
- **Microsoft Office files** (Word, Excel, PowerPoint)
- **Other cloud storage file types**

<Tip>
    **Questions, problems, feedback?** Please reach out in the [Slack community](https://nango.dev/slack).
</Tip>
